feat(api): document measured-power contract and add powerValid filter | API：文档化实测功率契约并新增 powerValid 筛选参数 - #938
Conversation
…t | 常量：提取 MEASURED_POWER_METRIC_KEYS 作为需扣留的实测功耗指标集合 Move the 13 measured power / energy / GPU-telemetry keys out of the METRIC_KEYS literal into an exported MEASURED_POWER_METRIC_KEY_LIST (and ReadonlySet MEASURED_POWER_METRIC_KEYS) so the ingest scrub and the display-layer withholding share one source of truth. METRIC_KEYS membership is unchanged (spread keeps the same entries); the contract discriminators power_valid / power_metric_schema_version and the invalid-verdict companion fields power_invalid_reasons / power_audit are codified as never part of the withheld set. 将 13 个实测功耗/能耗/GPU 遥测指标键从 METRIC_KEYS 字面量中提取为导出的 MEASURED_POWER_METRIC_KEY_LIST（及 ReadonlySet 形式的 MEASURED_POWER_METRIC_KEYS），使摄取端剥离逻辑与前端展示层扣留逻辑共享 单一事实来源。METRIC_KEYS 成员保持不变；契约判别字段与无效判定伴随字段 经测试固定永不进入扣留集合。
… ETL：power_valid=0 时在摄取阶段剥离实测功耗指标 Defense-in-depth for the power publication contract (G8). Today the only protections are producer-side stripping (aggregate_power.py) and the frontend display withholding — the ETL persists, and the raw API serves, whatever measured values a power_valid=0 artifact carries. Add scrubWithheldPowerMetrics to mapBenchmarkRow: after the normalized verdict fails closed to 0, delete every MEASURED_POWER_METRIC_KEYS entry and drop the workers payload. The scrub runs after the last metrics mutation (agentic preferFullResponseMetrics reassignment + extractRuntimeMetadata merge), covers every ingest path (CI ingest and both re-mapping backfills), is idempotent, and converges re-ingested dirty artifacts to exactly what a clean producer would ship. Verdict discriminators, companion fields (power_invalid_reasons / power_audit), legacy no-verdict rows, and pv=1 rows are untouched. The query layer deliberately stays unfiltered (single enforcement point at ETL). 针对功耗发布契约的纵深防御（G8）。此前仅有生产端剥离与前端展示扣留两道 防线：power_valid=0 的工件若携带实测值，ETL 会照常入库、原始 API 会照常 返回。本次在 mapBenchmarkRow 中新增 scrubWithheldPowerMetrics：判定值 归一化为 0 后，删除 MEASURED_POWER_METRIC_KEYS 中的全部指标并丢弃 workers 载荷。剥离在最后一次 metrics 变更之后执行，覆盖所有摄取路径， 幂等且使脏工件重摄取后与清洁生产端输出完全一致。判别字段、伴随字段、 无判定的历史行及 power_valid=1 的行均不受影响；查询层有意保持不过滤 （ETL 为唯一强制点）。
…KEYS | 测试：前端展示层扣留逻辑与 MEASURED_POWER_METRIC_KEYS 保持一致 Drive rowToAggDataEntry with a power_valid=0 row carrying every key in the shared constant and assert each corresponding output field (and workers) comes back undefined — adding a key to the constant that the frontend forgets to withhold now fails this test. The reverse direction (frontend withholding a key missing from the constant) stays hand-audited, as noted in the test comment. 以携带共享常量中全部键的 power_valid=0 行驱动 rowToAggDataEntry，断言 对应输出字段（含 workers）均为 undefined —— 若向常量新增了前端未扣留的 键，此测试即失败。反向情况（前端扣留了常量之外的键）仍由人工审计，测试 注释中已注明。
…apBenchmarkRow 的补充数据摄取同样应用功耗剥离 Review found ingest-supplemental.ts persists metrics verbatim via bulkIngestBenchmarkRows without mapBenchmarkRow, so a supplemental entry carrying power_valid=0 plus measured values would have bypassed the scrub. Export normalizePowerContractMetrics / scrubWithheldPowerMetrics and run the same fail-closed normalize+scrub pair on supplemental metrics; correct the scrub docstring to name the path; pin the direct-call usage with unit tests.
…量：导出 POWER_METRIC_KEYS 功率契约指标键列表 Derives the full documented power surface (discriminators + MEASURED_POWER_METRIC_KEY_LIST) as one exported constant and spreads it into METRIC_KEYS, keeping set membership provably unchanged. The public API documentation layer types BenchmarkRow.metrics from this export.
…enchmarks | API：为 /api/v1/benchmarks 新增 powerValid 实测功率有效性筛选参数 Pure post-cache row filter (cache keys unchanged): 1 keeps validated rows, 0 keeps explicitly invalidated rows, any is the default identity (legacy rows included), and strictV2 additionally requires power_metric_schema_version == 2 (whole-deployment energy semantics). Named strictV2 rather than certified to avoid colliding with the UI tier's product meaning. Unknown values 400; the combination with view=calculator 400s because the calculator cache stores rows already trimmed past power_valid. Route digest bumped in the review ledger.
… | 文档：为 /api/v1/benchmarks 文档化实测功率契约 Types every POWER_METRIC_KEYS entry on the BenchmarkRow metrics schema (additionalProperties still admits non-power keys), reserves the forthcoming power_invalid_reasons / power_audit row fields from the cross-plan producer contract, documents the previously-undocumented view/sequence params plus the new powerValid param, adds a bilingual measured-power schema note (tri-state power_valid, schema-version-2 whole-deployment energy, workers[] relationship, strictV2-vs-UI divergence), and mirrors the parameter list in the stable contract ledger. Cypress asserts the note and param render on /api and /zh/api.
…00 | 文档：说明 powerValid=any 可与 view=calculator 组合的例外 Review finding: the route only rejects non-any powerValid with view=calculator, but the published copy claimed the combination is always invalid. Align the operation description, the powerValid param description, and the 400 response description (EN + ZH) with actual behavior.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Claude finished @edwingao28's task in 2m 46s —— View job Review complete — 🟢 LGTM
No blocking or warning issues found. This is a clean, backward-compatible, well-tested change. What I verified at runtime (dev server, real read-only DB)
The unknown-value 400 short-circuits before the DB query, and the calculator-combination rejection is correctly ordered after it (an unknown value beats the combination error). Filter is a pure post-cache pass with no cache-key changes, so no blob-cache fragmentation. Correctness notes
Test coverageStrong. New colocated Chinese copyAll six changed zh passages reviewed against their English sources — accurate and natural for the API-reference surface. No fidelity or naturalness findings; no maintainer escalation needed. NoteStacked PR — as the description states, this must land after #937 ( |
中文：清理功耗剥离相关测试与实现注释，移除内部计划编号，并保留关键的故障关闭与摄取顺序语义。
中文：清理内部规划标签和冗余叙述，并以当前契约语义明确功率审计字段说明。
中文：合并更新后的功耗剥离基础分支并保留公开 API 契约
|
Claude finished @edwingao28's task in 2m 10s —— View job Re-review — 🟢 LGTM
What changed since the last review ( Runtime verification (dev server, real read-only DB)
The unknown-value 400 short-circuits before the calculator-combination 400 (verified), and the filter is a pure post-cache pass with no cache-key changes. Notes
No blocking or warning issues found. |
中文：解决 API 功率契约与 master 的合并冲突。
|
Claude finished @edwingao28's task in 1m 31s —— View job Re-review — 🟢 LGTM
What changed since the last LGTM ( CI status
The merge-gate caveat from the prior reviews is now resolved — the dedicated Runtime verification (dev server, real read-only DB)
Error ordering is correct: unknown-value 400 short-circuits before the calculator-combination 400; the filter is a pure post-cache pass with no cache-key changes. No blocking or warning issues found. Wait for the E2E workflow to go green before merge. |
仅接受 strictV2 作为公开功率筛选值；省略参数时保留常规基准结果。同步更新中英文文档、OpenAPI 契约和回归测试。
|
Claude finished @edwingao28's task in 2m 0s —— View job Re-review — 🟢 LGTM
What changed since the last LGTM (
CI status
Runtime verification (dev server, real read-only DB)
Test coverageAdequate and updated in lockstep: Chinese copyThe new commit rewrote the ZH Note: this narrows an accepted-value set relative to the earlier state of this same (unmerged) PR, so there's no external contract break — but it does mean |
1 participant
Summary | 概要
Adds a typed, documented measured-power contract to the public benchmarks API. The only explicit power filter is
powerValid=strictV2; the transitional1,0, andanymodes have been removed before rollout.为公开基准测试 API 提供带类型、有文档的实测功率契约。唯一接受的显式功率筛选值为
powerValid=strictV2；上线前移除过渡性的1、0和any选项。Final API contract | 最终 API 契约
GET /api/v1/benchmarks?model=DeepSeek-R1-0528&powerValid=strictV2keeps only rows with numericmetrics.power_valid === 1and numericmetrics.power_metric_schema_version === 2.仅保留
metrics.power_valid为数字1、且metrics.power_metric_schema_version为数字2的数据行。powerValidfor ordinary benchmark requests. Throughput and latency results remain available even when power is missing or invalid.常规基准测试请求省略
powerValid。即使功率缺失或无效，也会保留吞吐量和延迟结果。1,0,any,certified, and the empty string, returns HTTP 400Unknown powerValid filter.其他显式取值（包括上述旧选项及空字符串）均返回 HTTP 400
Unknown powerValid filter。powerValid=strictV2cannot be combined withview=calculator, because calculator projections omit the power verdict. Calculator requests still work whenpowerValidis omitted.计算器投影不包含功率验证字段，因此不能与
powerValid=strictV2组合使用；省略powerValid的计算器请求不受影响。Implementation | 实现
POWER_METRIC_KEYSidentifies the 15 power, energy, and GPU-telemetry keys without changingMETRIC_KEYSmembership.POWER_METRIC_KEYS统一列出 15 个功率、能耗及 GPU 遥测指标键，不改变METRIC_KEYS的成员集合。power_invalid_reasons/power_auditfields, schema-v2 whole-deployment energy semantics, and theview,sequence, andpowerValidparameters.OpenAPI 与中英文 API 页面同步说明指标、可选验证详情字段、schema v2 的整个部署能耗口径，以及相关查询参数。
最新结果、历史快照及指定运行查询均在读取共享缓存后筛选；不改变缓存键、数据库存储或常规响应行为。
master.fix(etl): strip measured power metrics at ingest when power_valid=0 | ETL：power_valid=0 时在摄取阶段剥离实测功耗指标 #937 已合并，本 PR 现以
master为目标分支。Scope | 范围
This retires public filter options, not the producer's internal valid/invalid verdict fields. Dashboard measured-power defaults and the UI's broader Certified tier are unchanged. This API change does not itself certify new measurements or supply missing producer telemetry/provenance.
本次移除的是公开筛选选项，不是生产端内部的有效/无效判定字段。仪表盘实测功率默认值及界面中范围更宽的 Certified 档位保持不变。本次 API 变更本身不会认证新的测量结果，也不会补齐生产端缺失的遥测或溯源数据。
Validation | 验证
全工作区单元测试：5,712 项通过。
Cypress 夹具模式快速冒烟检查：46 项组件检查及 113 项集成检查通过。
api-documentation.cy.ts: 4 passed, covering English/Chinese pages, OpenAPI, strict filtering, rejected values, omission, and calculator compatibility.定向 API 文档测试：4 项通过，覆盖中英文页面、OpenAPI、严格筛选、无效取值、省略参数及计算器兼容行为。
类型检查、静态检查、格式、排版及差异检查均通过。
Rollback | 回滚
Revert this PR. No migrations, cache-key changes, or data writes.
回退本 PR 即可；不涉及数据库迁移、缓存键变更或数据写入。
Note
Medium Risk
Changes a stable public benchmarks endpoint and published OpenAPI contract; behavior is backward compatible when
powerValidis omitted, but clients using new filters or relying on undocumented calculator params need correct combinations.Overview
Adds a documented measured-power surface and an optional
powerValidfilter onGET /api/v1/benchmarks. Omitting the parameter leaves responses unchanged;powerValid=strictV2keeps only rows withmetrics.power_valid === 1andmetrics.power_metric_schema_version === 2. Any other value (including empty) returns 400Unknown powerValid filter;powerValidcannot be combined withview=calculatorbecause calculator rows are trimmed before power fields exist.OpenAPI and the
/apipages gain typed 15 power-relatedmetricskeys viaPOWER_METRIC_KEYS, optional row fieldspower_invalid_reasonsandpower_audit, formally documentedview/sequence, and a bilingual Measured power schema note. Filtering runs post-cache throughbenchmark-power-validity.ts; the route catalog digest and contract parameter list are updated. Unit, documentation, and Cypress tests cover filter behavior and the published contract.Reviewed by Cursor Bugbot for commit 9814321. Bugbot is set up for automated code reviews on this repo. Configure here.